home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / haeberli / jpeg / codingrules < prev    next >
Text File  |  1994-08-01  |  4KB  |  100 lines
  1.  
  2.     JPEG SYSTEM CODING RULES        27-SEP-91
  3.  
  4. Since numerous people will be contributing code and bug fixes, it's important
  5. to establish a common coding style.  The goal of using similar coding styles
  6. is much more important than the details of just what that style is.
  7.  
  8. I suggest we follow the recommendations of "Recommended C Style and Coding
  9. Standards" revision 6.1 (Cannon et al. as modified by Spencer, Keppel and
  10. Brader).  I have placed a copy of this document in the jpeg FTP archive (see
  11. jpeg/doc/cstyle.ms.tbl.Z, or cstyle.txt.Z for those without nroff/tbl).
  12.  
  13. Unless someone has a real strong objection, let's do block comments thusly:
  14.  
  15. /*
  16.  *  Block comments in this style.
  17.  */
  18.  
  19. and indent statements in K&R style, e.g.,
  20.  
  21.     if (test) {
  22.         then-part;
  23.     } else {
  24.         else-part;
  25.     }
  26.  
  27. I suggest that multi-word names be written in the style multi_word_name
  28. rather than multiWordName, but I am open to argument on this.
  29.  
  30.  
  31. I would like to use function prototypes everywhere, and rely on automatic
  32. source code transformation to feed non-ANSI C compilers.  The best tool
  33. I have so far found for this is 'ansi2knr.c', which is part of Ghostscript.
  34. ansi2knr is not very bright, so it imposes a format requirement on function
  35. declarations: the function name MUST BEGIN IN COLUMN 1.  Thus all functions
  36. should be written in the following style:
  37.  
  38. static int *
  39. function_name (int a, char *b)
  40. {
  41.     code...
  42. }
  43.  
  44. ansi2knr won't help with method declarations (function pointers in structs).
  45. I suggest we use a macro to declare method pointers, something like this:
  46.  
  47. #ifdef PROTO
  48. #define METHOD(type,methodname,arglist)  type (*methodname) arglist
  49. #else
  50. #define METHOD(type,methodname,arglist)  type (*methodname) ()
  51. #endif
  52.  
  53. which is used like this:
  54.  
  55. struct function_pointers {
  56.     METHOD(void, init_entropy_encoder, (functptrs fptrs, jparms *jp));
  57.     METHOD(void, term_entropy_encoder, (void));
  58. };
  59.  
  60. Note the set of parentheses surrounding the parameter list.
  61.  
  62. A similar solution is used for external function declarations (see the PP
  63. macro in jpegdata.h).
  64.  
  65. If the code is to work on non-ANSI compilers, you cannot rely on a prototype
  66. declaration to coerce actual parameters into the right types.  Therefore, use
  67. explicit casts on actual parameters whenever the actual parameter type is not
  68. identical to the formal parameter.  Beware of implicit conversions to "int".
  69.  
  70. It seems there are some non-ANSI compilers in which the sizeof() operator
  71. is defined to return int, while size_t is defined as long.  Needless to say,
  72. this is brain-damaged.  Always use the SIZEOF() macro in place of sizeof(),
  73. so that the result is guaranteed to be of type size_t.
  74.  
  75.  
  76. We can expect that the JPEG compressor and decompressor will be incorporated
  77. into larger programs.  Therefore, the following rules are important:
  78.  
  79. 1. Avoid direct use of any file I/O, "malloc", error report printouts, etc;
  80. pass these through the common routines provided.
  81.  
  82. 2. Assume that the JPEG code may be invoked more than once per program run;
  83. therefore, do not rely on static initialization of variables, and be careful
  84. to release all allocated storage at the end of processing.
  85.  
  86. 3. Minimize global namespace pollution.  Functions should be declared static
  87. wherever possible.  (Note that our method-based calling conventions help this
  88. a lot: in many modules only the method-selector function will ever need to be
  89. called directly, so only that function need be externally visible.)  All
  90. global function names should begin with "j", and should be unique in the first
  91. six characters for portability reasons.
  92. Don't use global variables at all; anything that must be used in another
  93. module should be put into parameters (there'll be some large structs passed
  94. around for this purpose).
  95.  
  96. 4. Source file names should also begin with "j"; remember to keep them to
  97. eight characters (plus ".c" or ".h", etc) to make life easy for MS-DOSers.
  98. Do not put code for both compression and decompression into the same source
  99. file.
  100.